

Tulip software graph format (TLP)

Definition of the TLP format version

The first line of the file must indicate the version of the format (since Tulip 3.6, the current version is 2.3). This definition encloses all the needed graph definitions (nodes, edges ...) and so the corresponding closing parenthesis must be found at the end of the file. Comments lines begin with a semi-colon (;).
Syntax

(tlp "2.3"

; the rest of the file
...

)

Additional file informations

The date, the author name and some comments can be added. For convenience they are automatically added when saving or exporting a graph using the Tulip graphical user interface.
Syntax

(date | author | comments "a string")

Sample

(date "09-11-2006")
(author "pm")
(comments "This file was generated by Tulip.")

Definition of nodes

First, in order to improve the nodes vector allocation, the number of nodes can be indicated.
Syntax

(nb_nodes n)

Sample

(nb_nodes 5)

It indicates that the graph has five nodes.


Then the nodes are declared as a list of indices. The indices must be non negative integers and for the root graph they must be consecutive integers beginning at index 0. As a shortcut when specifying a list of consecutive indices, only the first and last indices can be indicated separated by '..' .
Syntax

(nodes id_node1 id_node2 ...)

Sample

(nodes 0 1 2 3 4)

This defines five nodes with index from 0 to 4, and can also be declared as follows

(nodes 0..4)

Definition of edges

An edge is defined by providing three non negative integers. The first is the id of the edge, the second is the id of source node of the edge and the third is the id of target node of the edge. Two edges cannot have the same id. The ids of edges must be must be consecutive integers beginning at index 0.
Syntax

(edge id id_source id_target)

Sample

(edge 2 2 1)

It defines one edge with the node having the id 2 as source and the node with id 1 as target.
Definition of sub-graphs or clusters

A cluster is defined by an integer which indicated the cluster id. Then it is defined with a list of nodes and a list of edges which all must have been previously defined as element of the root graph. As a shortcut when specifying a list of consecutive indices, only the first and last indices can be indicated separated by '..' . To define a subcluster the same method is used. The cluster id 0 is reserved for the root graph and thus it cannot be used.
Syntax

(cluster id
  (nodes id_node1 id_node2 ...)
  (edges id_edge1 id_edge2 ...)
  (cluster id
    (nodes id_node1 id_node2 ...)
    (edges id_edge1 id_edge2 ...)
  )
)

Sample

(cluster 3
  (nodes 1..3)
  (edges 2 8)
  (cluster 4
    (nodes 1 2)
    (edges 2)
  )
)

A name can be assigned to a cluster using the graph_attributes definition
Syntax

(graph_attributes clusted_id
  (string "name" cluster_name)
)

Sample

(graph_attributes 1
   (string "name" "sub-graph 1")
)


Definition of properties

The definition of a property is the following:
Syntax

(property cluster_id property_type "property_name"
  (default "default_node_value" "default_edge_value" )
  (node id value)
  ...
  (edge id value)
  ...
)

Sample

(property 0 bool "viewSelection"
  (default "false" "false" )
  (node 1 "true")
  (node 2 "true")
  (node 3 "true")
  (edge 2 "true")
  (edge 8 "true")
)

Property Type

The existing types are the following

    bool : This type is used to store boolean on elements.
    color : This type is used to store the color of elements. The color is defined with a sequence of four integer from 0 to 255. "(red,green,blue,alpha)"
    double : This is used to store 64 bits real on elements.
    layout : This type is used to store 3D nodes position. The position of nodes is defined by a set of 3 doubles "(x_coord,y_coord,z_coord)". The position of edges is a list of 3D points. These points are the bends of edges. "((x_coord1,y_coord1,z_coord1)(x_coord2,y_coord2,z_coord2))"
    int : This type is used to store integers on elements.
    size : This type is used to store the size of elements. The size is defined with a sequence of three double. "(width,heigth,depth)"
    string : This is used to store text on elements.


Some vector<type> exists too. They allow two store a vector of values on graph elements.

    vector<bool> : This type is used to store a vector of booleans on elements.
    vector<color> : This type is used to store a vector of color (as previously defined) on elements.
    vector<coord> : This type is used to store a vector of coordinates (as a set of 3 doubles "(x_coord,y_coord,z_coord)") on elements.
    vector<double> : This is used to store a vector of 64 bits real on elements.
    vector<int> : This type is used to store a vector of integers on elements.
    vector<size> : This type is used to store a vector of size (as previously defined) on elements.
    vector<string> : This is used to store a vector of texts on elements.


Properties with the same name can be defined for different clusters.
Tulip's predefined properties

    "viewColor" type color, this property is the used for coloring graphs in Tulip.
    Sample

    (property 0 color "viewColor"
      (default "(235,0,23,255)" "(0,0,0,0)" )
      (node 1 "(200,0,200,255)")
      (node 2 "(100,100,0,255)")
      (node 3 "(100,100,0,255)")
      (edge 2 "(200,100,100)")
    )

    "viewLabel" type string, this property is the one used for labeling the graphs in Tulip(in label mode).
    Sample

    (property 0 string "viewLabel"
      (default "" "" )
      (node 1 "Hello")
      (node 2 "Bonjour")
      (node 3 "Bye")
      (edge 2 "Aurevoir")
    )

    "viewLayout" type layout, this property is the one used for displaying graph in Tulip.
    Sample

    (property 0 layout "viewLayout"
      (default "(0,0,0)" "()" )
      (node 1 "(10,10,10)")
      (node 2 "(20,20,20)")
      (edge 1 "(15,15,15)(25,25,25)")
    )

    "viewSelection" type bool, this property is the one used for selected elements in Tulip.
    Sample

    (property 0 bool "viewSelection"
      (default "false" "false" )
      (node 1 "true")
      (node 2 "true")
      (node 3 "true")
      (edge 2 "true")
      (edge 8 "true")
    )

    "viewSize" type size, this property is the one used for the size of elements displayed.
    Sample

    (property 0 size "viewSize"
      (default "(0,0,0)" "(1,1,1)" )
      (node 1 "(10,10,10)")
      (node 2 "(20,20,20)")
    )

    "viewShape" type int, this property is used for defining the shape of elements.
    Sample

    (property 0 int "viewShape"
      (default "0" "0" )
      (node 1 "1")
      (node 2 "2")
    )


